<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 22.1</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="22.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="22.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P3">Part III. The Standard Libraries</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#22">Chapter 22. The Operating System Library</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h2>22.1 &ndash; Date and Time</h2>

<p>Two functions, <code>time</code> and <code>date</code>,
do all date and time queries in Lua.

<p>The <code>time</code> function,
when called without arguments,
returns the current date and time,
coded as a number.
(In most systems,
that number is the number of seconds since some epoch.)
When called with a table,
it returns the number representing the
date and time described by the table.
Such <em>date tables</em> have the following significant fields:
<p><table align="center" border=1>
<tr><td><code>year</code></td><td>a full year</td></tr>
<tr><td><code>month</code></td><td>01-12</td></tr>
<tr><td><code>day</code></td><td>01-31</td></tr>
<tr><td><code>hour</code></td><td>01-31</td></tr>
<tr><td><code>min</code></td><td>00-59</td></tr>
<tr><td><code>sec</code></td><td>00-59</td></tr>
<tr><td><code>isdst</code></td><td>a boolean, <B>true</B> if daylight saving</td></tr>
</table><p>
The first three fields are mandatory;
the others default to noon (12:00:00) when not provided.

In a Unix system (where the epoch is 00:00:00 UTC, January 1, 1970)
running in Rio de Janeiro (which is three hours west of Greenwich),
we have the following examples:
<pre>
    -- obs: 10800 = 3*60*60 (3 hours)
    print(os.time{year=1970, month=1, day=1, hour=0})
      --> 10800
    print(os.time{year=1970, month=1, day=1, hour=0, sec=1})
      --> 10801
    print(os.time{year=1970, month=1, day=1})
      --> 54000   (obs: 54000 = 10800 + 12*60*60)
</pre>

<p>The <code>date</code> function, despite its name,
is a kind of a reverse of the <code>time</code> function:
It converts a number representing the date and time
back to some higher-level representation.
Its first parameter is a <em>format string</em>,
describing the representation we want.
The second is the numeric date-time;
it defaults to the current date and time.

<p>To produce a date table,
we use the format string <code>"*t"</code>.
For instance, the following code
<pre>
    temp = os.date("*t", 906000490)
</pre>
produces the table
<pre>
    {year = 1998, month = 9, day = 16, yday = 259, wday = 4,
     hour = 23, min = 48, sec = 10, isdst = false}
</pre>
Notice that, besides the fields used by <code>os.time</code>,
the table created by <code>os.date</code> also gives the week day
(<code>wday</code>, 1 is Sunday)
and the year day (<code>yday</code>, 1 is January 1).

<p>For other format strings, <code>os.date</code> formats the date as a string,
which is a copy of the format string where specific tags are
replaced by information about time and date.
All tags are represented by a `<code>%</code>&acute; followed by a letter,
as in the next examples:
<pre>
    print(os.date("today is %A, in %B"))
      --> today is Tuesday, in May
    print(os.date("%x", 906000490))
      --> 09/16/1998
</pre>
All representations follow the current locale.
Therefore, in a locale for Brazil-Portuguese,
<code>%B</code> would result in <code>"setembro"</code>
and <code>%x</code> in <code>"16/09/98"</code>.

<p>The following table shows each tag, its meaning,
and its value for September 16, 1998 (a Wednesday),
at 23:48:10.
For numeric values, the table shows also their range of possible values:
<p><table align="center" border=1>
<tr><td><code>%a</code></td><td>abbreviated weekday name (e.g., <code>Wed</code>)</td></tr>
<tr><td><code>%A</code></td><td>full weekday name (e.g., <code>Wednesday</code>)</td></tr>
<tr><td><code>%b</code></td><td>abbreviated month name (e.g., <code>Sep</code>)</td></tr>
<tr><td><code>%B</code></td><td>full month name (e.g., <code>September</code>)</td></tr>
<tr><td><code>%c</code></td><td>date and time (e.g., <code>09/16/98 23:48:10</code>)</td></tr>
<tr><td><code>%d</code></td><td>day of the month (<code>16</code>) [01-31]</td></tr>
<tr><td><code>%H</code></td><td>hour, using a 24-hour clock (<code>23</code>) [00-23]</td></tr>
<tr><td><code>%I</code></td><td>hour, using a 12-hour clock (<code>11</code>) [01-12]</td></tr>
<tr><td><code>%M</code></td><td>minute (<code>48</code>) [00-59]</td></tr>
<tr><td><code>%m</code></td><td>month (<code>09</code>) [01-12]</td></tr>
<tr><td><code>%p</code></td><td>either <code>"am"</code> or <code>"pm"</code> (<code>pm</code>)</td></tr>
<tr><td><code>%S</code></td><td>second (<code>10</code>) [00-61]</td></tr>
<tr><td><code>%w</code></td><td>weekday (<code>3</code>) [0-6 = Sunday-Saturday]</td></tr>
<tr><td><code>%x</code></td><td>date (e.g., <code>09/16/98</code>)</td></tr>
<tr><td><code>%X</code></td><td>time (e.g., <code>23:48:10</code>)</td></tr>
<tr><td><code>%Y</code></td><td>full year (<code>1998</code>)</td></tr>
<tr><td><code>%y</code></td><td>two-digit year (<code>98</code>)  [00-99]</td></tr>
<tr><td><code>%%</code></td><td>the character `<code>%</code>&acute;</td></tr>
</table><p>

<p>If you call <code>date</code> without any arguments,
it uses the <code>%c</code> format, that is,
complete date and time information in a reasonable format.
Note that the representations for <code>%x</code>,
<code>%X</code>, and <code>%c</code> change according to the locale and the system.
If you want a fixed representation,
such as <code>mm/dd/yyyy</code>,
use an explicit format string, such as <code>"%m/%d/%Y"</code>.

<p>The <code>os.clock</code> function returns the number of seconds of
CPU time for the program.
Its typical use is to benchmark a piece of code:
<pre>
    local x = os.clock()
    local s = 0
    for i=1,100000 do s = s + i end
    print(string.format("elapsed time: %.2f\n", os.clock() - x))
</pre>

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="22.2.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

